
<html>
  
  <HEAD>
    
    <link rel="stylesheet" href="style/default.css" type="text/css">
    
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  
    <title>JAXB RI 2.1.4 fcs -- Using XJC with Ant
    </title>
    <link rel="alternate" href="https://jaxb.dev.java.net/servlets/ProjectNewsRSS" type="application/rss+xml">
  </HEAD>

  
  <BODY>
    <h1>
      <banner>
    Java
        <sup>
          <font size="-2">TM</font>
        </sup> Architecture for XML Binding
  
      </banner>
      <br>
      Using XJC with Ant 
    
    </h1>
    <center>
      <b>Implementation Version:</b> 2.1.4 fcs
      <br>
    </center>
    <table class="navbar" cellspacing="0">
      <tr>
        <td class="inactive">
          <a href="index.html">JAXB 2.0</a>
        </td>
        <td class="active">
          <a>Tools</a>
        </td>
        <td class="inactive">
          <a href="jaxb-1_0.html">JAXB 1.0.x</a>
        </td>
        <td class="inactive">
          <a href="vendor.html">JAXB RI Extensions</a>
        </td>
        <td class="inactive">
          <a href="community.html">JAXB Community</a>
        </td>
      </tr>
    </table>
    <div class="subnavbar">
      <ul>
        <li class="first">
          <a href="xjc.html">
            <span>XJC </span>
          </a>
        </li>
        <li>
          <a href="xjcTask.html">
            <span class="active">XJC Ant Task </span>
          </a>
        </li>
        <li>
          <a href="schemagen.html">
            <span>SchemaGen </span>
          </a>
        </li>
        <li>
          <a href="schemagenTask.html">
            <span>SchemaGen Ant Task </span>
          </a>
        </li>
        <li>
          <a href="3rdparty.html">
            <span>3rd Party Tools </span>
          </a>
        </li>
      </ul>
    </div>
    
    <header></header>


    
    <p>The 
      <code>jaxb-xjc.jar</code> file contains the 
      <code>XJCTask.class</code> file, which allows 
       the XJC binding compiler to be invoked from the 
      <a href="http://jakarta.apache.org/ant">Ant</a> build tool. To use 
       
      <code>XJCTask</code>, 
       include the following statement in your 
      <code>build.xml</code> file:
    

        
    <pre class="ant-example">
&lt;taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask"&gt;
  &lt;classpath&gt;
    &lt;fileset dir="path/to/jaxb/lib" includes="*.jar" /&gt;
  &lt;/classpath&gt;
&lt;/taskdef&gt;
</pre>

    
    <p>This maps 
      <code>XJCTask</code> to an Ant task named 
      <code>xjc</code>.  For 
       detailed examples of using this task, refer to any of the 
      <tt>build.xml</tt> 
       files used by the 
      <a href="samples.html">sample applications</a>.
    

    
    <h2>Synopsis</h2>

    
    <h3>Environment Variables</h3>
      
    <ul>
        
      <li>
        <a href="http://wiki.apache.org/ant/TheElementsOfAntStyle">ANT_OPTS</a> - command-line arguments that should be passed to the JVM. For 
            example, you can define system properties or set the maximum Java heap 
            size here.
      </li>
      
    </ul>

    
    <h3>Parameter Attributes</h3>
    
    <p>
      <code>xjc</code> supports the following parameter attributes.
    

    
    <table summary="" border="1">
      
      <thead>
        
        <tr>
          
          <td>
            <b>Attribute</b>
          </td>
          
          <td>
            <b>Description</b>
          </td>
          
          <td>
            <b>Required</b>
          </td>
        
        </tr>
      
      </thead>

      
      <tbody>
        
        <tr>
          
          <td>schema</td>
          
          <td>A schema file to be compiled. A file name (can be relative to the build script base directory), or an URL.</td>
          
          <td>This or nested &lt;
            <tt>schema</tt>&gt; elements are required.
          </td>
        
        </tr>
        
        <tr>
          
          <td>binding</td>
          
          <td>An external binding file that will be applied to the schema 
              file.</td>
          
          <td>No</td>
        
        </tr>
        
        <tr>
          
          <td>package</td>
          
          <td>If specified, generated code will be placed under this Java
              package. This option is equivalent to the "-p"
              command-line switch.</td>
          
          <td>No</td>
        
        </tr>
        
        <tr>
          
          <td>destdir</td>
          
          <td>Generated code will be written under this directory. If you
              specify 
            <code>target="abc/def"</code> and 
            <code>package="org.acme"</code>, 
              then files are generated to 
            <code>abc/def/org/acme</code>.
          </td>
          
          <td>Yes</td>
        
        </tr>
        
        <tr>
          
          <td>readonly</td>
          
          <td>Generate Java source files in the read-only mode if 
            <code>true</code> 
              is specified. 
            <code>false</code> by default.
          </td>
          
          <td>No</td>
        
        </tr>
        
        <tr>
          
          <td>header</td>
          
          <td>Generate a header in each generated file indicating that this file
              is generated by such and such version of JAXB RI when. 
            <code>true</code> by default.
          </td>
          
          <td>No</td>
        
        </tr>
        
        <tr>
          
          <td>extension</td>
          
          <td>If set to 
            <tt>true</tt>, the XJC binding compiler will run in the extension mode. Otherwise, it 
              will run in the strict conformance mode. Equivalent of the 
              "
            <code>-extension</code>" command line switch. The default is
              
            <code>false</code>.
          </td>
          
          <td>No</td>
        
        </tr>
        
        
        <tr>
          
          <td>catalog</td>
          
          <td>
            Specify the catalog file to resolve external entity references.
            Support TR9401, XCatalog, and OASIS XML Catalog format. See the catalog-resolver
            sample for details.
          </td>
          
          <td>No</td>
        
        </tr>
        
        <tr>
          
          <td>removeOldOutput</td>
          
          <td>Used in pair with nested 
            <code>&lt;produces&gt;</code> elements. When 
              this attribute is specified as "
            <tt>yes</tt>", the files pointed to by the 
              
            <code>&lt;produces&gt;</code> elements will be all deleted before the XJC binding compiler 
              recompiles the source files. See the up-to-date check section for 
              details.
          </td>
          
          <td>No</td>
        
        </tr>
        
        <tr>
          
          <td>source</td>
          
          <td>Specify which version of the schema compiler to use.  Must be either "1.0", "2.0", or "2.1".
              The compiler will parse XML Schema and bind them according to the rules specified by the given version of the specification. Note that 2.1 is backward compatible with 2.0, so these two flags won't make any difference.
          </td>
          <td>No, defaults to "2.1"</td>
        
        </tr>
        
        <tr>
          
          <td>target
            <img src="new.gif">
          </td>
          
          <td>Specifies the runtime environment in which the generated code is supposed to run. This value must be smaller than the 
            <tt>source</tt> attribute, if specified (IOW, you can't do 
            <tt>source="1.0" target="2.0"</tt>) This allows more up-to-date versions of XJC to be used for developing applications that run on earlier JAXB versions.
          </td>
          
          <td>No, defaults to "2.1"</td>
      
        
        </tr>
        <tr>
          
          <td>language
            <img src="new.gif">
          </td>
          
          <td>Specifies the schema language to compile. Supported values are "WSDL", "XMLSCHEMA", and "WSDL." Case insensitive</td>
          
          <td>No, defaults to "XMLSCHEMA"</td>
      
    
        </tr>
      </tbody>
    </table>

		
    <h3>Nested Elements</h3>
		
    <div class="nested-elements">
    
      <p>
        <code>xjc</code> supports the following nested element parameters.
      

	  
      <h4>schema</h4>
	
	  
      <p>To compile more than one schema at the same time, use a nested 
        <code>
	     &lt;schema&gt;</code> element, which has the same syntax as 
        <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">
          <code>
         &lt;fileset&gt;</code>
        </a>.
      
	
	  
      <h4>binding</h4>
	
	  
      <p>To specify more than one  external binding file at the same time, use a 
	     nested 
        <code>&lt;binding&gt;</code> element, which has the same syntax as
         
        <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">
          <code>
         &lt;fileset&gt;</code>
        </a>.
      
	
	  
      <h4>classpath</h4>
	
	  
      <p>To specify locations of the user-defined classes necessary during the 
	     compilation (such as an user-defined type that is used through a 
	     
        <code>&lt;javaType&gt;</code> customization), use nested 
        <code>&lt;classpath&gt;
	     </code> elements. For the syntax, see 
        <a href="http://jakarta.apache.org/ant/manual/using.html#path">"path-like structure"
	     </a>.
      
	
	  
      <h4>arg</h4>
	
	  
      <p>Additional command line arguments passed to the XJC. For details 
	     about the syntax, see 
	     
        <a href="http://ant.apache.org/manual/using.html#arg">the relevant 
	     section</a> in the Ant manual. This nested element can be used to 
	     specify various options not natively supported in the 
        <tt>xjc</tt> 
	     Ant task.  For example, currently
there is no native support for 
	     the following 
        <tt>xjc</tt> command-line options:
	     
        <ul>
	     
          <li>
            <tt>-nv</tt>
          </li>
	     
          <li>
            <tt>-use-runtime</tt>
          </li>
	     
          <li>
            <tt>-schema</tt>
          </li>
	     
          <li>
            <tt>-dtd</tt>
          </li>
	     
          <li>
            <tt>-relaxng</tt>
          </li>
	     
          <li>
            <tt>-Xlocator</tt>
          </li>
	     
          <li>
            <tt>-Xsync-methods</tt>
          </li>
	     
        </ul>
	     
	  
      
      <p>To use any of these features from the 
        <tt>xjc&gt;</tt> Ant task, you 
	     must specify the appropriate nested &lt;
        <tt>arg</tt>&gt; elements.
	  
      
	
      
      <h4>depends</h4>
	
      
      <p>Files specified with this nested element will be taken into account when the 
         XJC task does the up-to-date check. See the up-to-date check section for 
         details. For the syntax, see 
        <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">
          <code>
         &lt;fileset&gt;</code>
        </a>.
      
	
	  
      <h4>produces</h4>
	
	  
      <p>Files specified with this nested element will be taken into account when the 
	     XJC task does the up-to-date check. See the up-to-date check section for 
	     details. For the syntax, see 
        <a href="http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html">
          <code>
	     &lt;fileset&gt;</code>
        </a>.
      
	  
	  
      <h4>xmlcatalog</h4>
	  
      <p>The 
        <a href="http://ant.apache.org/manual/CoreTypes/xmlcatalog.html">xmlcatalog</a> element is used to resolve entities when parsing schema documents.
      
    
    </div>


    
    <h2>Generated Resource Files</h2>
    
    <p>Please see the 
      <a href="xjc.html#xjcresources">xjc page</a> for more detail.
    
    
    
    <h2>Up-to-date Check</h2>
    
    <p>By default, the XJC binding compiler always compiles the inputs. 
       However, with a little additional setting, it can compare timestamps of 
       the input files and output files and skip compilation if the files are 
       up-to-date.
    
    <p>Ideally, the program should be able to find out all the inputs and 
       outputs and compare their timestamps, but this is difficult and 
       time-consuming.  So you have to tell the task input files and output files 
       manually by using nested 
      <code>&lt;depends&gt;</code> and 
      <code>&lt;produces&gt;</code> 
       elements. Basically, the XJC binding compiler compares the timestamps specified by the 
      <code>
       &lt;depends&gt;</code> elements against those of the 
      <code>&lt;produces&gt;</code> set. 
       If any one of the "depends" file has a more recent timestamp than some of the files 
       in the "produces" set, it will compile the inputs. Otherwise it will skip the 
       compilation.
    
    
    <p>This will allow you to say, for example "if any of the 
      <tt>.xsd</tt> 
       files in this directory are newer than the 
      <tt>.java</tt> files in that directory, 
       recompile the schema".
    
    
    <p>Files specified as the schema files and binding files are automatically added 
       to the "depends" set as well, but if those schemas are including/importing other 
       schemas, you have to use a nested 
      <code>&lt;depends&gt;</code> elements. No files 
       are added to the 
      <code>&lt;produces&gt;</code> set, so you have to add all of them 
       manually.
    
    
    <p>A change in a schema or an external binding file often results in a Java file that 
       stops being generated. To avoid such an "orphan" file, it is often desirable to 
       isolate all the generated code into a particular package and delete it before 
       compiling a schema. This can be done by using the 
      <code>removeOldOutput</code> 
       attribute. This option allows you to remove all the files that match the 
       "produces" filesets before a compilation. 
      <em>Be careful when you use this 
       option so that you don't delete important files</em>.
    
    

    
    <h2>Schema Language Support</h2>
    
    <p>This release of the JAXB RI includes experimental support for RELAX NG, DTD, and
    WSDL.  To compile anything other than W3C XML Schema from the 
      <tt>xjc</tt> Ant task,
    you must use the nested &lt;
      <tt>arg</tt>&gt; element to specify the appropriate command line
    switch, such as "
      <tt>-dtd</tt>", "
      <tt>-relaxng</tt>", or "
      <tt>-wsdl</tt>".  Otherwise, your input schemas will
    be treated as W3C XML Schema and the binding compiler will fail.

    
    
    <h2>Examples</h2>
    
    <p>Compile 
      <code>myschema.xsd</code> and place the generated files under 
       
      <code>src/org/acme/foo</code>:
    


    <pre class="ant-example">
&lt;xjc schema="src/myschema.xsd" target="src" package="org.acme.foo"/&gt;
</pre>

    
    <p>Compile all XML Schema files in the 
      <code>src</code> directory and place the 
       generated files under the appropriate packages in the 
      <code>src</code> 
       directory:
    


    <pre class="ant-example">
&lt;xjc target="src"&gt;
  &lt;schema  dir="src" includes="*.xsd"/&gt;
&lt;/xjc&gt;
</pre>

    
    <p>Compile all XML Schema files in the 
      <code>src</code> directory together with 
       binding files in the same directory and places the generated files under the 
       appropriate packages in the 
      <code>src</code> directory. This example assumes 
       that binding files contain package customizations. This example doesn't search 
       subdirectories of the 
      <code>src</code> directory to look for schema files.
    


    <pre class="ant-example">
&lt;xjc target="src"&gt;
  &lt;schema  dir="src" includes="*.xsd"/&gt;
  &lt;binding dir="src" includes="*.xjb"/&gt;
&lt;/xjc&gt;
</pre>


    
    <p>Compile 
      <code>abc.xsd</code> with an up-to-date check. Compilation only happens 
    when 
      <code>abc.xsd</code> is newer than any of the files in the 
      <code>
    src/org/acme/foo</code> directory (and its 
      <code>impl</code> subdirectory). Files 
    in these two directories will be wiped away before a compilation, so 
      <em>don't add 
    your own code in those directories</em>. Note that the additional 
      <code>mkdir</code> 
    task is necessary because Ant's fileset requires the directory specified by the 
    
      <code>dir</code> attribute to exist.
    


    <pre class="ant-example">
&lt;mkdir dir="src/org/acme/foo" /&gt;
&lt;xjc target="src" schema="abc.xsd" removeOldOutput="yes" package="org.acme.foo"&gt;
  &lt;produces dir="src/org/acme/foo" includes="* impl/*" /&gt;
&lt;/xjc&gt;
</pre>


    
    <p>More complicated example of up-to-date check. In this example, we assume that
    you have a large set of schema documents that reference each other, with DTDs that
    describe the schema documents. An explicit &lt;depends&gt; is necessary so that when you update one of the DTDs, XJC will recompile your schema. But &lt;depends&gt; don't have to re-specify all the schema files, because you've already done that via &lt;schema&gt;.


    <pre class="ant-example">
&lt;mkdir dir="src/org/acme/foo" /&gt;
&lt;xjc target="src" removeOldOutput="yes" package="org.acme.foo"&gt;
  &lt;schema dir="schema" includes="*.xsd" /&gt;
  &lt;depends dir="schema" includes="*.dtd" /&gt;
  &lt;produces dir="build/generated-src/org/acme/foo" includes="**/*" /&gt;
&lt;/xjc&gt;
</pre>

    
    <p>Compile all XML Schema files in the 
      <code>src</code> directory and subdirectories, 
       excluding files named 
      <code>debug.xsd</code>, and place the generated files under 
       the appropriate packages in the 
      <code>src</code> directory. This example also 
       specifies the "
      <tt>-nv</tt>" option, which disables the strict schema correctness checking:
    


    <pre class="ant-example">
&lt;xjc target="src"&gt;
  &lt;schema dir="src" includes="**/*.xsd" excludes="**/debug.xsd"/&gt;
  &lt;arg value="-nv" /&gt;
&lt;/xjc&gt;
</pre>

    
    <p>If you depend on a proxy server to resolve the location of imported or included 
       schemas (as you might if you're behind a firewall), you need to make the hostname 
       and port number accessible to the JVM hosting 
      <code>ant</code>. Do this by setting 
       the environment variable 
      <code>ANT_OPTS</code> to a string containing the 
       appropriate 
      <code>java</code> options. For example, from DOS:
    


    <pre class="ant-example">
&gt; set ANT_OPTS=-Dhttp.proxyHost=webcache.east
&gt; set ANT_OPTS=%ANT_OPTS% -Dhttp.proxyPort=8080
&gt; ant
</pre>

	
    <hr>
	
    <div class="footer">
	  $Revision: 1.7.4.4 $
      <br>
	  $Date: 2006/11/09 23:45:04 $
	
    </div>
  



  </BODY>
</html>